OpenEdge Development:<br />ADM and SmartObjects SmartDataBrowser usage notes

This section discusses special programming considerations for using SmartDataBrowsers.

The NO-ASSIGN property

The NO-ASSIGN property in the design window of a SmartDataBrowser master or the property sheet for the browse widget is set to TRUE. This allows the ADM code to handle all record updates.

Default triggers for SmartDataBrowsers

The master procedure file for a SmartDataBrowser defines a variety of triggers for the browse widget that it contains:

OFF-END ({src/adm2/brsoffnd.i}) — Checks whether there are more rows in the query in the forward direction.

OFF-HOME ({src/adm2/brsoffhm.i}) — Checks whether there are more rows in the query in the backward direction.

END ({src/adm2/brsend.i}) — Performs a fetchLast operation.

HOME ({src/adm2/brshome.i}) — Performs a fetchFirst operation.

CTRL-END — Applies the END trigger, which performs a fetchLast operation, to the browse (does not have an include file of its own).

CTRL-HOME ({src/adm2/brshome.i}) — Applies the HOME trigger, which performs a fetchFirst operation, to the browse (does not have an include file of its own).

ROW-ENTRY ({src/adm2/brsentry.i}) — Displays the initial values for newly added or copied rows.

ROW-LEAVE ({src/adm2/brsleave.i}) — If the selected object is not a SmartPanel button (for example, a Cancel or Reset button), saves any changes made to the row, otherwise the button takes the action associated with the button.

VALUE-CHANGED ({src/adm2/brschnge.i}) — Instructs the SmartDataObject linked to the browse to let other objects know that the record has changed.

SCROLL-NOTIFY ({src/adm2/brsscrol.i}) — Checks whether there are more rows in the query in the forward direction.

Scrolling past the end of the result set

The SmartDataBrowser’s OFF-END and OFF-HOME triggers produce certain visual anomalies when your users browse the associated SmartDataObject query’s result set and try to scroll past the end of the result set.

When a SmartDataBrowser browses a SmartDataObject query, the associated RowObject temp-table might contain only a subset of the entire database query result set at any given time, so the SmartDataBrowser might browse only that subset. Although the supporting trigger code for the SmartDataBrowser is designed to make this as transparent as possible, the retrieval of multiple batches of rows into the SmartDataObject’s RowObject temp-table has some visible impact on the SmartDataBrowser.

In particular, the OFF-END trigger fires when the browse is scrolled to the bottom of the current result set, which happens when the application user does one of the following:

Presses the DOWN arrow on the keyboard in an attempt to scroll beyond the last row in the current result set.

Presses the down arrow on the SmartDataBrowser’s vertical scroll bar until the last row is reached, then releases the arrow.

When the OFF-END event occurs, the SmartDataBrowser code asks the SmartDataObject whether there are more rows to retrieve from the database. If so, an additional batch of rows is added to the RowObject temp-table, the temp-table’s query is reopened, and the browse is repositioned to the same row as before the event. This causes a delay (normally a brief one) while the records are retrieved and the query is reopened. It also means that the user must release the scroll bar arrow to see more rows.

If the SmartDataObject’s RebuildOnRepos instance property is set to YES, an attempt to scroll past the end of the result set might occur in either a forward or a backward direction. For example, if RebuildOnRepos is YES, and the application user either presses the Last button on a SmartPanel or SmartToolbar or presses CTRL-END on the keyboard to move to the last row in the result set, the RowObject table in the SmartDataObject is rebuilt from the end. Thus, if the user scrolls backwards (upwards) to the first row in the current result set, the OFF-HOME event causes the retrieval of the next batch of rows before the current result set, which causes a similar delay as the user scrolls up through the data. The vertical scroll bar might be similarly inconsistent and not reflect the size of the complete data set.

These visual anomalies are necessary to allow a client without a database connection to browse a potentially large result set without the entire data set being moved to the client at one time. If you do not want them to occur in your application, do one of the following:

Set the SmartDataObject’s RowsToBatch instance property to retrieve the entire data set at one time.

Set its RebuildOnRepos instance property to build the result set in a single direction from beginning to end.

Multiple selection

Multiple selection is not supported for SmartDataBrowsers. If you want to use this option, you must add supporting code to communicate the multiple selection to other SmartObjects as needed.

Setting the dynamic SmartDataBrowser field properties

Once you link a dynamic SmartDataBrowser to a SmartDataObject, you can set the SmartDataBrowser’s DisplayedFields and EnabledFields instance properties in its instance properties dialog box. The ADM uses the values at run time to determine the display and update fields for the SmartDataBrowser. Setting only one or neither property has these results:

If you set DisplayedFields but not EnabledFields, and the SmartDataBrowser has a TableIO-Source (an Update SmartPanel), EnabledFields is set at run time to a list of all specified DisplayedFields in the associated SmartDataObject’s UpdatableColumns property. Otherwise, it is made blank (that is, there are no EnabledFields).

If you set EnabledFields but not DisplayedFields, and the SmartDataBrowser has a TableIO-Source (an Update SmartPanel), DisplayedFields is set at run time to a list of all fields in the associated SmartDataObject’s DataColumns property.

If you leave both properties unset, the UpdatableColumns property is set only if there is a TableIO-Source.

The dynamic SmartDataBrowser SearchField property

The dynamic SmartDataBrowser has a property called SearchField that is not available in the static SmartDataBrowser. This property allows you to specify a field on which to search at run time. If you specify a value, the first line of the SmartDataBrowser frame is allocated to a fill-in field in which the user can enter a search value at run time. The SmartDataObject query is automatically re-sorted by the SearchField value, and on each keystroke entered, the browse is repositioned to the first row whose search field has a value greater than or equal to the user-specified search value.

Displaying row markers in the dynamic SmartDataBrowser

Unchecking the NO-ROW-MARKERS property in the property sheet for the dynamic SmartDataBrowser does not display row markers (the expected behavior of this browser). You can get row markers, however, by explicitly setting ROW-MARKERS to YES in dynbrowser.w. Specifically, add the following code to the main block of dynbrowser.w: